Repository navigation
Conversation
L'API est servie intégralement par server-nestjs : les endpoints V1 /api/v1/environments et /api/v1/repositories ne sont pas repris (équivalents V2 sous /api/v2/projects/:projectId/), le Swagger historique /swagger-ui renvoie 404 au profit de /swagger-ui-server-nestjs, l'authentification navigateur passe par un jeton Bearer Keycloak résolu côté backend, et une date d'expiration vide à la création d'un jeton d'API équivaut à l'absence d'expiration. Co-authored-by: Automata <automata@shikanime.studio>
StephaneTrebel
left a comment
StephaneTrebel
left a comment
There was a problem hiding this comment.
La mise à jour indique utilement les anciens accès API retirés et le Swagger à utiliser ; mes remarques non bloquantes visent surtout à séparer les sujets et à rendre le texte lisible sans connaissance du backend. Liens locaux vérifiés et CI « Test app build » verte ; pas de build local ni de recette API exécutés, et le complément d’exploitation reste suivi séparément dans #135 (sans ledger propre à cette MR).
| L’IAM repose sur Keycloak pour l’identité (OIDC), une authentification backend via session ou jeton API, et une autorisation calculée côté serveur avec des bitmasks BigInt. | ||
|
|
||
| L’authentification navigateur passe par `fastify-keycloak-adapter`, qui extrait l’identité (`sub`, `email`, `given_name`, `family_name`, `groups`) et la stocke en session. Un mode jeton API (`x-dso-token`) existe aussi pour des usages non interactifs. | ||
| L’authentification navigateur s’appuie sur Keycloak (OIDC) : le client attache un jeton `Authorization: Bearer` émis par Keycloak et le backend résout l’identité du jeton (`sub`, `email`, `given_name`, `family_name`, groupes OIDC). Un mode jeton API (`x-dso-token`) existe aussi pour des usages non interactifs. |
There was a problem hiding this comment.
⚪ suggestion (lisibilité): Expliquer la connexion avant les détails du protocole
« Le client attache un jeton » et « le backend résout l’identité » supposent de connaître le fonctionnement d’une application web. Proposition :
Lorsqu’un utilisateur se connecte, Keycloak lui fournit un jeton d’accès. L’application web transmet ce jeton à l’API dans l’en-tête
Authorization: Bearer <jeton>. Le serveur vérifie le jeton et en extrait l’identité de l’utilisateur. Pour les scripts et les outils automatisés, un jeton d’API peut être transmis dans l’en-têtex-dso-token.
Les noms techniques des champs (sub, given_name…) peuvent rester dans une seconde phrase destinée aux intégrateurs, plutôt que d’interrompre l’explication de base.
| L’authentification navigateur passe par `fastify-keycloak-adapter`, qui extrait l’identité (`sub`, `email`, `given_name`, `family_name`, `groups`) et la stocke en session. Un mode jeton API (`x-dso-token`) existe aussi pour des usages non interactifs. | ||
| L’authentification navigateur s’appuie sur Keycloak (OIDC) : le client attache un jeton `Authorization: Bearer` émis par Keycloak et le backend résout l’identité du jeton (`sub`, `email`, `given_name`, `family_name`, groupes OIDC). Un mode jeton API (`x-dso-token`) existe aussi pour des usages non interactifs. | ||
|
|
||
| L’API de la Console est désormais servie intégralement par le backend NestJS : les anciens endpoints V1 `/api/v1/environments` et `/api/v1/repositories` ne sont pas repris, utilisez leurs équivalents V2 sous `/api/v2/projects/:projectId/`. Le Swagger historique `/swagger-ui` n’est plus servi (404) ; la documentation d’API maintenue est disponible à `/swagger-ui-server-nestjs`. À la création d’un jeton d’API, une date d’expiration laissée vide est acceptée et équivaut à l’absence d’expiration. |
There was a problem hiding this comment.
⚪ suggestion (structure): Séparer les trois informations et donner les chemins de remplacement complets
Ce paragraphe mélange migration des routes, accès à la documentation et expiration des jetons. Un lecteur cherchant une seule de ces informations doit tout déchiffrer ; « sous /api/v2/projects/:projectId/ » ne donne pas encore les routes à appeler.
Je proposerais un petit bloc « Si vous utilisez l’API », avec :
- un tableau anciennes routes → routes V2 complètes (
…/:projectId/environmentset…/:projectId/repositories), en précisant que:projectIdest à remplacer par l’identifiant du projet ; - « Consultez la documentation interactive de l’API à l’adresse
/swagger-ui-server-nestjs. L’ancienne adresse/swagger-uirenvoie désormais une erreur 404. » ; - une phrase séparée sur les jetons : « Si vous laissez la date d’expiration vide, le jeton reste valable sans limite de durée. »
Cela évite aussi les termes non expliqués « endpoints » et « Swagger » comme seuls points de repère.
| L’IAM repose sur Keycloak pour l’identité (OIDC), une authentification backend via session ou jeton API, et une autorisation calculée côté serveur avec des bitmasks BigInt. | ||
|
|
||
| L’authentification navigateur passe par `fastify-keycloak-adapter`, qui extrait l’identité (`sub`, `email`, `given_name`, `family_name`, `groups`) et la stocke en session. Un mode jeton API (`x-dso-token`) existe aussi pour des usages non interactifs. | ||
| L’authentification navigateur s’appuie sur Keycloak (OIDC) : le client attache un jeton `Authorization: Bearer` émis par Keycloak et le backend résout l’identité du jeton (`sub`, `email`, `given_name`, `family_name`, groupes OIDC). Un mode jeton API (`x-dso-token`) existe aussi pour des usages non interactifs. |
There was a problem hiding this comment.
🟡 nit (cohérence): Aligner aussi la phrase de synthèse sur l’authentification décrite ici
Le nouveau texte remplace la session par un jeton Bearer :
-L’authentification navigateur passe par `fastify-keycloak-adapter`, qui extrait l’identité (`sub`, `email`, `given_name`, `family_name`, `groups`) et la stocke en session. Un mode jeton API (`x-dso-token`) existe aussi pour des usages non interactifs.
+L’authentification navigateur s’appuie sur Keycloak (OIDC) : le client attache un jeton `Authorization: Bearer` émis par Keycloak et le backend résout l’identité du jeton (`sub`, `email`, `given_name`, `family_name`, groupes OIDC). Un mode jeton API (`x-dso-token`) existe aussi pour des usages non interactifs.Mais la ligne juste au-dessus annonce toujours une « authentification backend via session ou jeton API ». Harmoniser cette synthèse avec le nouveau paragraphe éviterait de faire croire à deux mécanismes navigateur concurrents.
Quoi
Mise à jour de la page IAM (
docs/platform/iam.md) pour refléter l'état actuel de la Console :fastify-keycloak-adapteret un stockage en session, ce qui ne décrit plus le flux servi par server-nestjs ;/api/v1/environmentset/api/v1/repositories(équivalents V2 sous/api/v2/projects/:projectId/) ;/swagger-ui(404), remplacé par/swagger-ui-server-nestjs;Pourquoi
La Console sert désormais toute son API via le backend NestJS : le trafic applicatif legacy est fermé (console#2927) et les routes admin tokens et system settings ont été basculées vers server-nestjs (commits console 5618a220, ab27124a, 85eecbb4). Par ailleurs, le schéma de création de jeton accepte de nouveau une date d'expiration vide (commit eea6fd6a). La page décrivait encore l'ancien flux de cohabitation des deux backends.
Références